Add agent discoverability surfaces#18
Closed
mikedotexe wants to merge 3 commits into
Closed
Conversation
Deploying builder-docs with
|
| Latest commit: |
0fef871
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://7018604e.builder-docs.pages.dev |
| Branch Preview URL: | https://codex-agent-discoverability.builder-docs.pages.dev |
This live smoke test asserts HTTP Link headers and content-negotiated .md serving advertised via static/_headers and static/_worker.js, which only execute on Cloudflare Pages with Workers/Pages Functions. Note this in a header comment so future readers know that a failure against the GitHub Pages origin is by design and not a regression. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
mikedotexe
force-pushed
the
codex/agent-discoverability-core
branch
from
April 25, 2026 19:10
1dbcff0 to
0fef871
Compare
This was referenced Apr 25, 2026
Collaborator
Author
|
Closing to clear the board — the branch Why not merge as-is:
Note the human-facing agent surfaces already landed on main ( |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR adds
Static metadata and tooling that lets AI agents and crawlers self-bootstrap to FastNear's surfaces, plus a generator and audit pipeline to keep it consistent.
static/.well-known/agent-skills/{index.json + 4 SKILL.md}— agentskills.io v0.2.0 discovery directory (overview,surface-routing,auth,playbooks)static/.well-known/api-catalog— RFC 8615 linkset for RPC, FastNear API, and NEARData (withservice-desc,service-doc,statusper service)src/data/openapiSnapshots/{fastnear,neardata}.json(canonical, hand-vendored) →static/openapi/{fastnear,neardata}.json(build mirror viacopyOpenApiSnapshots()inscripts/generate-ai-surfaces.js)static/_headers— advertises the discovery surfaces via HTTPLinkheaders (RFC 8615 / agent-skills) on every routestatic/_worker.js— serves.mdmirrors via content negotiation (Accept: text/markdown) and adds the matchingLinkheadersstatic/robots.txt— adds Cloudflare AI Content Signals:Content-Signal: search=yes, ai-input=yes, ai-train=yesscripts/generate-ai-surfaces.js— extended (~233 lines) to drive the artifacts above; SKILL.md files also pick up the existing "About FastNear" footer CTAscripts/audit-indexing-surface.js— extended (~509 lines) to validate the new static surface area; runs inci:locale-qualitypost-build (no new CI gating beyond what's already there)scripts/audit-agent-readiness-live.js+audit:agent-readiness:live— manual live smoke test against the deployed origin, validates theLinkheaders and.mdcontent negotiation are wired correctlyHosting
docs.fastnear.comis on Cloudflare Pages (visible from the repo'sCloudflare PagesGitHub status check), sostatic/_headersandstatic/_worker.jsare load-bearing — they execute on the edge once this merges. No infra change required.Current branch status
Rebased onto current
main(post#20and#21example-tightening merges). Two real fixes surfaced from the rebase + regen:SKILL.mdfiles now correctly include the "About FastNear" footer CTA that landed onmainafter this branch was first opened.static/ru/**markdown caught up tomain's tightened example content.Verification
yarn buildclean (en + ru both compile)node scripts/audit-indexing-surface.jsclean against local build (Indexing surface audit passed for 105 explicit docs routes, 78 docs operation pages, and 78 hosted operation pages.)yarn generate:ai-surfacesis idempotent: re-running produces no further drift—escaping vs raw em-dash fromJSON.stringifyre-encoding — but semantically identical)ci:locale-qualityor any otherci:*/audit:*aggregateTest plan
yarn buildexits 0 for both localesnode scripts/audit-indexing-surface.jsexits 0 against the local build treeSITE_ORIGIN=https://docs.fastnear.com node scripts/audit-agent-readiness-live.jsexits clean (validatesLinkheaders,.well-known/api-catalog,.well-known/agent-skills/index.json, and.mdcontent negotiation are live)Out of scope for this PR
audit:agent-readiness:liveinto CI (kept manual until we trust the live signal across a few deploys)src/data/openapiSnapshots/(manual snapshot maintenance for now; document a sync cadence in a follow-up)